package com.smart.community.property.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.commons.result.PageResult;
import com.smart.community.property.entity.GasFee;
import com.smart.community.property.vo.GasFeeVO;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;
import java.util.Map;

/**
 * 燃气费服务接口
 * @author Wu.Liang
 * @since 2024-12-21
 */
public interface IGasFeeService extends IService<GasFee> {
    
    /**
     * 分页查询燃气费账单
     * @param current 当前页
     * @param size 每页大小
     * @param communityId 社区ID
     * @param paymentStatus 支付状态
     * @return 分页结果
     * @throws Exception 统一异常
     */
    PageResult<GasFee> getGasFeePage(Integer current, Integer size,
                                     Long communityId, Integer paymentStatus) throws Exception;
    
    /**
     * 根据房户ID查询最新的表读数
     * @param householdId 房户ID
     * @return 最新表读数
     * @throws Exception 统一异常
     */
    GasFee getLatestReadingByHouseholdId(Long householdId) throws Exception;
    
    /**
     * 根据用户ID查询未缴费燃气费账单
     * @param userId 用户ID
     * @return 未缴费账单列表
     * @throws Exception 统一异常
     */
    List<GasFee> getUnpaidGasFeesByUserId(Long userId) throws Exception;
    
    /**
     * 燃气费缴费
     * @param billId 账单ID
     * @param paymentAmount 支付金额
     * @param paymentMethod 支付方式
     * @return 是否缴费成功
     * @throws Exception 统一异常
     */
    boolean payGasFee(Long billId, BigDecimal paymentAmount, Integer paymentMethod) throws Exception;
    
    /**
     * 生成燃气费账单
     * @param communityId 社区ID
     * @param billingMonth 计费月份
     * @param unitPrice 燃气单价
     * @return 生成的账单数量
     * @throws Exception 统一异常
     */
    int generateGasFee(Long communityId, LocalDate billingMonth, BigDecimal unitPrice) throws Exception;
    
    /**
     * 生成燃气费账单（重载方法，支持String类型的计费月份）
     * @param communityId 社区ID
     * @param billingMonth 计费月份（yyyy-MM格式）
     * @param unitPrice 燃气单价
     * @return 生成的账单数量
     * @throws Exception 统一异常
     */
    int generateGasFee(Long communityId, String billingMonth, BigDecimal unitPrice) throws Exception;
    
    /**
     * 提交燃气表读数
     * @param householdId 房户ID
     * @param reading 表读数
     * @param readingDate 读数日期
     * @return 是否提交成功
     * @throws Exception 统一异常
     */
    boolean submitMeterReading(Long householdId, BigDecimal reading, LocalDate readingDate) throws Exception;
    
    /**
     * 发送燃气费催缴提醒
     * @param billId 账单ID
     * @param remindType 提醒方式
     * @return 是否发送成功
     * @throws Exception 统一异常
     */
    boolean sendGasReminder(Long billId, String remindType) throws Exception;
    
    /**
     * 批量发送燃气费催缴提醒
     * @param communityId 社区ID
     * @param remindType 提醒方式
     * @return 发送结果统计
     * @throws Exception 统一异常
     */
    Map<String, Integer> batchSendGasReminder(Long communityId, String remindType) throws Exception;
    
    /**
     * 批量提交燃气表读数
     * @param communityId 社区ID
     * @param meterReadings 表读数数据
     * @return 提交结果统计
     * @throws Exception 统一异常
     */
    Map<String, Integer> batchSubmitMeterReading(Long communityId, List<Map<String, Object>> meterReadings) throws Exception;
    
    /**
     * 燃气安全检查
     * @param communityId 社区ID
     * @return 安全检查结果
     * @throws Exception 统一异常
     */
    Map<String, Object> gasSafetyCheck(Long communityId) throws Exception;
    
    /**
     * 获取燃气费统计信息
     * @param communityId 社区ID
     * @param year 年份
     * @return 统计信息
     * @throws Exception 统一异常
     */
    Map<String, Object> getGasFeeStatistics(Long communityId, Integer year) throws Exception;
    
    /**
     * 查询逾期燃气费账单
     * @param communityId 社区ID
     * @return 逾期账单列表
     * @throws Exception 统一异常
     */
    List<GasFee> getOverdueGasFees(Long communityId) throws Exception;
    
    /**
     * 查询异常用量记录
     * @param communityId 社区ID
     * @return 异常用量记录
     * @throws Exception 统一异常
     */
    List<GasFee> getAbnormalUsageRecords(Long communityId) throws Exception;
    
    /**
     * 计算燃气费金额（按用量阶梯等计算）
     * @param usageAmount 用量
     * @param unitPrice 单价
     * @return 计算后的费用金额
     * @throws Exception 统一异常
     */
    BigDecimal calculateGasFee(BigDecimal usageAmount, BigDecimal unitPrice) throws Exception;
    
    // ==================== 移动端专用方法 ====================
    
    /**
     * 查询当前用户的燃气费账单（App端专用）
     * 
     * 严格按照《Java后端SpringBoot代码开发规范.md》Service规范：
     * - 异常往外抛：移除try-catch异常处理，添加throws Exception声明
     * - 详细的日志记录，包括开始、成功状态
     * - 完善的权限验证和业务逻辑验证
     * - 完整的JavaDoc注释
     * 
     * 数据权限：判断当前登录用户是否为此房户的业主
     * 
     * @param current 当前页
     * @param size 每页大小
     * @param paymentStatus 缴费状态
     * @param billingPeriod 计费周期
     * @return 分页查询结果
     * @throws Exception 统一异常
     */
    PageResult<GasFeeVO> getMyGasFees(Integer current, Integer size, 
                                      Integer paymentStatus, String billingPeriod) throws Exception;
    
    /**
     * 获取燃气费详情（App端专用）
     * 
     * 严格按照《Java后端SpringBoot代码开发规范.md》Service规范：
     * - 异常往外抛：移除try-catch异常处理，添加throws Exception声明
     * - 验证用户权限，只能查看自己的费用记录
     * - 增加对账单存在性的验证
     * 
     * 数据权限：判断当前登录用户是否为此房户的业主
     * 
     * @param billId 账单ID
     * @param userId 用户ID
     * @return 账单详情
     * @throws Exception 统一异常
     */
    GasFeeVO getGasFeeDetailForMobile(Long billId, Long userId) throws Exception;
    
    /**
     * 验证用户权限（App端专用）
     * 
     * 验证当前用户是否为该房户的业主，确保数据安全
     * 
     * @param feeId 费用ID
     * @param userId 用户ID
     * @throws Exception 统一异常
     */
    void validateUserPermissionForFee(Long feeId, Long userId) throws Exception;
} 